home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 18 / CU Amiga Magazine's Super CD-ROM 18 (1997)(EMAP Images)(GB)[!][issue 1998-01].iso / CUCD / Online / hsc / docs-source / fileargs.hsc < prev    next >
Encoding:
Text File  |  1997-10-10  |  4.8 KB  |  143 lines
  1. <WEBPAGE chapter="hsc - " title="File Options"
  2.     PREV="examples.html"
  3.     NEXT="messages.html">
  4.  
  5. There are several CLI-options to specify where <hsc> should take the
  6. input from and where the output should be placed. This section
  7. describes the differences and (dis-)advantages.
  8.  
  9. <H2>Converting Single Files</H2>
  10.  
  11. This one uses a single file for input and output:
  12. <PRE>
  13.     hsc FROM hugo.hsc TO hugo.html
  14. </PRE>
  15. It will use <FILE>hugo.hsc</FILE> and outputs to <FILE>hugo.html</FILE>.
  16. Both input and output will be located in the current directory. This can
  17. be useful if you only want to quickly process a single file trough <hsc>,
  18. and do not want to set up a complete project.
  19.  
  20. <H2>Using Different Directories For Input And Output</H2>
  21.  
  22. <P>One of the features of <hsc> is that your object can be located at
  23. a totally different place from the source. This enables you to place
  24. your sources at a different disk as the one the w3-Server has access
  25. to, saving server space.</P>
  26.  
  27. For instance, you can use
  28.  
  29. <PRE>hsc FROM hugo.hsc TO www:sepp/hugo.html</PRE>
  30.  
  31. <P>to use <FILE>hugo.hsc</FILE>, located in the current directory, and
  32. create <FILE>www:sepp/hugo.html</FILE>. Note that all images,
  33. other documents etc. you reference from out <FILE>hugo.hsc</FILE> using
  34. relative URIs have to be located at the corresponding place within
  35. the directory <FILE>www:sepp/</FILE>.</P>
  36.  
  37. <P>For example, if <FILE>hugo.hsc</FILE> contains a tag
  38.  
  39. <$source pre><IMG SRC="image/back.gif" ALT="back"></$source>
  40.  
  41. the image file <FILE>back.gif</FILE> will have to be located at
  42. <FILE>www:sepp/image/back.gif</FILE>.
  43.  
  44. <H2>Using A Destination Directory</H2>
  45.  
  46. The same as above can be performed using
  47.  
  48. <PRE>hsc FROM hugo.hsc TO www:sepp/</PRE>
  49.  
  50. <P>Note the trailing slash that tells <hsc> that it should now output
  51. to a directory and determine the filename by itself. Usually, it
  52. will use (<CODE>input filename</CODE>, without <qqc>.hsc</qqc>,
  53. but a <qqc>.html</qqc> appended), resulting into <FILE>www:sepp/hugo.html</FILE>
  54. as before. You can change the default extension using the CLI option
  55. <op_extension>.</P>
  56.  
  57. <H2>Using Sub Directories</H2>
  58.  
  59. <P>For complex project, usually not all documents are located at the
  60. same directory. For example, <FILE>hugo.hsc</FILE> is no more
  61. placed in the current directory, but in 
  62. <FILE>people/hugo.hsc</FILE>.</P>
  63.  
  64. Invoking hsc like
  65.  
  66. <PRE>hsc FROM people/hugo.hsc TO www:sepp/</PRE>
  67.  
  68. <P>will now output to <FILE>www:sepp/people/hugo.html</FILE>. Note that you
  69. have to take care that the directory <FILE>www:sepp/people/</FILE>
  70. exists, <hsc> will not create any new directories by itself.</P>
  71.  
  72. If you now want to embed an image located at
  73. <FILE>www:sepp/image/back.gif</FILE> into this document, you have to
  74. use
  75.  
  76. <$source pre><IMG SRC="../image/back.gif" ALT="back"></$source>
  77.  
  78. Alternatively, you can use a <fe_prjuri>:
  79.  
  80. <$source pre><IMG SRC=":image/back.gif" ALT="back"></$source>
  81.  
  82. Another way to obtain the same result is using
  83.  
  84. <PRE>hsc FROM people/hugo.hsc TO www:sepp/people/hugo.html</PRE>
  85.  
  86. <P>In this case, <hsc> is smart enough to figure out that the
  87. destination directory is <FILE>www:sepp/</FILE>, and you are using
  88. <FILE>people/</FILE> as subdirectory.</P>
  89.  
  90. But if you try to use
  91.  
  92. <PRE>hsc FROM people/hugo.hsc TO www:sepp/stuff/hugo.html</PRE>
  93.  
  94. <hsc> can not figure out what to use as destination- or
  95. subdirectory, and will show up an error message:
  96.  
  97. <PRE>unmatched corresponding relative directories:
  98.   input  `people/'
  99.   output `stuff/'</PRE>
  100.  
  101. In this case, you will have to rename your directories.
  102.  
  103. <H2>Using Pipes</H2>
  104.  
  105. <P>Short: It is possible to use pipes with <hsc>, but it should be
  106. avoided in most cases; <hsc> isn't really <qq>pipable</qq>. It does not 
  107. continuously read data from the input and write parts of the output.</P>
  108.  
  109. <P>(<Technote>It reads the whole input file with a single call to
  110. <CODE>fread()</CODE>, creates the output in memory and writes it with
  111. (more or less) a single <CODE>fwrite()</CODE>. The main reasons why it
  112. works this way are: I hate to check for I/O errors,
  113. <CODE>fungetc()</CODE> usually does not work after a linefeed and
  114. memory mapped files are not supported by the standard ANSI
  115. library.)</P>
  116.  
  117. <P>Additionally, it impossible for <hsc> to maintain a project file
  118. without knowledge of the filenames for document and source, so 
  119. several features will be disabled.</P>
  120.  
  121. <P>If <hsc> needs to access relative URIs, it will have to use the
  122. current directory as starting point.</P>
  123.  
  124. <P>Therefor, pipes should only be used if you quickly want to test
  125. a feature on a single file or something like that.</P>
  126.  
  127. Anyway, here is an example:
  128.  
  129. <PRE>hsc STDIN</PRE>
  130.  
  131. This specifies the (case sensitive) pseudo-filename <KBD>STDIN</KBD>
  132. as input, which will use <stdin>. Missing a <KBD>TO</KBD> option, the
  133. output will be written to <stdout>. Now using this like
  134.  
  135. <$source PRE>hsc STDIN <hugo.hsc >hugo.html</$source>
  136.  
  137. would be equal to
  138.  
  139. <PRE>hsc hugo.hsc TO hugo.html</PRE>
  140.  
  141. Again: Try to avoid this.
  142. </WEBPAGE>
  143.